# Invite a user to join a group

Creates an invitation for a user to join the group. Only group owners and admins can create invitations.
            The invitee must not already be a member of the group or have a pending invitation.
            Exactly one of inviteeId or inviteeEmail must be provided.

            The response contains the created invite and an emailSent flag indicating whether
            an invitation email was sent from this server (false for remote users, whose home server sends the email).

RBAC: requires GroupMembers.Invite

Endpoint: POST /api/v1/groups/{groupId}/invites
Version: 1.0
Security: header

## Path parameters:

  - `groupId` (string, required)
    The unique identifier of the group
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

## Request fields (application/json):

  - `inviteeId` (string,null)
    ID of the user to invite
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `inviteeEmail` (string,null)
    Email address to invite (local users only)

  - `message` (string,null)
    Optional message to include with the invitation

## Response 200 fields (application/json):

  - `invite` (object, required)
    The created invitation

  - `invite.groupInviteId` (string, required)
    Unique identifier for this invitation
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `invite.groupId` (string, required)
    ID of the group
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `invite.inviterId` (string, required)
    ID of the user who sent the invitation
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `invite.inviteeId` (string,null)
    ID of the user being invited (null for email-only invites)
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `invite.status` (string, required)
    Current status of the invitation
    Enum: "PENDING", "ACCEPTED", "REJECTED"

  - `invite.message` (string,null)
    Optional message from the inviter

  - `invite.email` (string,null)
    Email address of the invitee (present for email-based invites)

  - `invite.inviterName` (string, required)
    Username of the inviter

  - `invite.inviterDisplayName` (string, required)
    Display name of the inviter

  - `invite.inviterAvatar` (object,null)
    Avatar of the inviter

  - `invite.inviterAvatar.uploadId` (string, required)
    Internal id
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `invite.inviterAvatar.uploaderId` (string,null)
    User who physically uploaded this file. Null for platform-owned uploads (e.g., default covers). This is an audit/meta field — use ownerId for authorization.
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `invite.inviterAvatar.ownerId` (string, required)
    Entity that owns this upload (user, channel/group, or event). TypeID prefix indicates the owner type.
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `invite.inviterAvatar.attachedToId` (string,null)
    Entity this upload is attached to (e.g., a post or event). NULL for standalone uploads like avatars, covers, or media library items.
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `invite.inviterAvatar.uploadType` (string, required)
    Type of the upload
    Enum: "VIDEO", "IMAGE", "AUDIO", "DOCUMENT", "OTHER"

  - `invite.inviterAvatar.meta` (object)
    Meta data

  - `invite.inviterAvatar.meta.blurhash` (string,null)

  - `invite.inviterAvatar.meta.name` (string,null)

  - `invite.inviterAvatar.meta.altText` (string,null)

  - `invite.inviterAvatar.size` (integer, required)
    Size in bytes of all the files in this upload

  - `invite.inviterAvatar.files` (array, required)
    List of all the files this upload has

  - `invite.inviterAvatar.files.uri` (string,null, required)
    Full url of the file

  - `invite.inviterAvatar.files.fileId` (string, required)
    File id
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `invite.inviterAvatar.files.extension` (string, required)
    File extension
    Example: "mp4"

  - `invite.inviterAvatar.files.original` (boolean, required)
    true if this file is original, false if it is a derivative

  - `invite.inviterAvatar.files.meta` (object, required)
    File metadata. Contains optional values for width, height etc.

  - `invite.inviterAvatar.files.meta.duration` (number,null)
    Video duration in seconds

  - `invite.inviterAvatar.files.meta.width` (integer,null)
    Media width

  - `invite.inviterAvatar.files.meta.height` (integer,null)
    Media height

  - `invite.inviterAvatar.files.meta.codec` (string,null)
    Video codec

  - `invite.inviterAvatar.files.meta.rotate` (integer,null)
    Rotation in degrees

  - `invite.inviterAvatar.files.size` (integer, required)
    File size in bytes

  - `invite.inviterAvatar.files.createdAt` (string, required)
    Example: "2022-03-10T16:15:50Z"

  - `invite.inviterAvatar.files.updatedAt` (string, required)
    Example: "2022-03-10T16:15:50Z"

  - `invite.inviterAvatar.files.type` (string, required)
    File type
    Enum: "VIDEO", "IMAGE", "AUDIO", "DOCUMENT", "OTHER"

  - `invite.inviterAvatar.tags` (array, required)
    List of tags attached to upload
    Enum: "Post", "Avatar", "Header", "Album", "Emoji", "Event"

  - `invite.inviterAvatar.error` (string,null)
    Upload processing error

  - `invite.inviterAvatar.cached` (boolean)
    true if cached

  - `invite.inviterAvatar.logs` (string,null)
    Logs

  - `invite.inviterAvatar.remote` (boolean)
    true if this upload is remote

  - `invite.inviterAvatar.createdAt` (string, required)
    Example: "2022-03-10T16:15:50Z"

  - `invite.inviterAvatar.updatedAt` (string, required)
    Example: "2022-03-10T16:15:50Z"

  - `invite.inviteeName` (string,null)
    Username of the invitee (null for unclaimed email-only invites)

  - `invite.inviteeDisplayName` (string,null)
    Display name of the invitee (null for unclaimed email-only invites)

  - `invite.inviteeAvatar` (object,null)
    Avatar of the invitee

  - `invite.inviteeAvatar.uploadId` (string, required)
    Internal id
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `invite.inviteeAvatar.uploaderId` (string,null)
    User who physically uploaded this file. Null for platform-owned uploads (e.g., default covers). This is an audit/meta field — use ownerId for authorization.
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `invite.inviteeAvatar.ownerId` (string, required)
    Entity that owns this upload (user, channel/group, or event). TypeID prefix indicates the owner type.
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `invite.inviteeAvatar.attachedToId` (string,null)
    Entity this upload is attached to (e.g., a post or event). NULL for standalone uploads like avatars, covers, or media library items.
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `invite.inviteeAvatar.uploadType` (string, required)
    Type of the upload
    Enum: "VIDEO", "IMAGE", "AUDIO", "DOCUMENT", "OTHER"

  - `invite.inviteeAvatar.meta` (object)
    Meta data

  - `invite.inviteeAvatar.meta.blurhash` (string,null)

  - `invite.inviteeAvatar.meta.name` (string,null)

  - `invite.inviteeAvatar.meta.altText` (string,null)

  - `invite.inviteeAvatar.size` (integer, required)
    Size in bytes of all the files in this upload

  - `invite.inviteeAvatar.files` (array, required)
    List of all the files this upload has

  - `invite.inviteeAvatar.files.uri` (string,null, required)
    Full url of the file

  - `invite.inviteeAvatar.files.fileId` (string, required)
    File id
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `invite.inviteeAvatar.files.extension` (string, required)
    File extension
    Example: "mp4"

  - `invite.inviteeAvatar.files.original` (boolean, required)
    true if this file is original, false if it is a derivative

  - `invite.inviteeAvatar.files.meta` (object, required)
    File metadata. Contains optional values for width, height etc.

  - `invite.inviteeAvatar.files.meta.duration` (number,null)
    Video duration in seconds

  - `invite.inviteeAvatar.files.meta.width` (integer,null)
    Media width

  - `invite.inviteeAvatar.files.meta.height` (integer,null)
    Media height

  - `invite.inviteeAvatar.files.meta.codec` (string,null)
    Video codec

  - `invite.inviteeAvatar.files.meta.rotate` (integer,null)
    Rotation in degrees

  - `invite.inviteeAvatar.files.size` (integer, required)
    File size in bytes

  - `invite.inviteeAvatar.files.createdAt` (string, required)
    Example: "2022-03-10T16:15:50Z"

  - `invite.inviteeAvatar.files.updatedAt` (string, required)
    Example: "2022-03-10T16:15:50Z"

  - `invite.inviteeAvatar.files.type` (string, required)
    File type
    Enum: "VIDEO", "IMAGE", "AUDIO", "DOCUMENT", "OTHER"

  - `invite.inviteeAvatar.tags` (array, required)
    List of tags attached to upload
    Enum: "Post", "Avatar", "Header", "Album", "Emoji", "Event"

  - `invite.inviteeAvatar.error` (string,null)
    Upload processing error

  - `invite.inviteeAvatar.cached` (boolean)
    true if cached

  - `invite.inviteeAvatar.logs` (string,null)
    Logs

  - `invite.inviteeAvatar.remote` (boolean)
    true if this upload is remote

  - `invite.inviteeAvatar.createdAt` (string, required)
    Example: "2022-03-10T16:15:50Z"

  - `invite.inviteeAvatar.updatedAt` (string, required)
    Example: "2022-03-10T16:15:50Z"

  - `invite.groupName` (string, required)
    Name of the group

  - `invite.groupDisplayName` (string, required)
    Display name of the group

  - `invite.groupAvatar` (object,null)
    Avatar of the group

  - `invite.groupAvatar.uploadId` (string, required)
    Internal id
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `invite.groupAvatar.uploaderId` (string,null)
    User who physically uploaded this file. Null for platform-owned uploads (e.g., default covers). This is an audit/meta field — use ownerId for authorization.
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `invite.groupAvatar.ownerId` (string, required)
    Entity that owns this upload (user, channel/group, or event). TypeID prefix indicates the owner type.
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `invite.groupAvatar.attachedToId` (string,null)
    Entity this upload is attached to (e.g., a post or event). NULL for standalone uploads like avatars, covers, or media library items.
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `invite.groupAvatar.uploadType` (string, required)
    Type of the upload
    Enum: "VIDEO", "IMAGE", "AUDIO", "DOCUMENT", "OTHER"

  - `invite.groupAvatar.meta` (object)
    Meta data

  - `invite.groupAvatar.meta.blurhash` (string,null)

  - `invite.groupAvatar.meta.name` (string,null)

  - `invite.groupAvatar.meta.altText` (string,null)

  - `invite.groupAvatar.size` (integer, required)
    Size in bytes of all the files in this upload

  - `invite.groupAvatar.files` (array, required)
    List of all the files this upload has

  - `invite.groupAvatar.files.uri` (string,null, required)
    Full url of the file

  - `invite.groupAvatar.files.fileId` (string, required)
    File id
    Example: "us_01hxcvk1hjexere4pvtrj0ymqq"

  - `invite.groupAvatar.files.extension` (string, required)
    File extension
    Example: "mp4"

  - `invite.groupAvatar.files.original` (boolean, required)
    true if this file is original, false if it is a derivative

  - `invite.groupAvatar.files.meta` (object, required)
    File metadata. Contains optional values for width, height etc.

  - `invite.groupAvatar.files.meta.duration` (number,null)
    Video duration in seconds

  - `invite.groupAvatar.files.meta.width` (integer,null)
    Media width

  - `invite.groupAvatar.files.meta.height` (integer,null)
    Media height

  - `invite.groupAvatar.files.meta.codec` (string,null)
    Video codec

  - `invite.groupAvatar.files.meta.rotate` (integer,null)
    Rotation in degrees

  - `invite.groupAvatar.files.size` (integer, required)
    File size in bytes

  - `invite.groupAvatar.files.createdAt` (string, required)
    Example: "2022-03-10T16:15:50Z"

  - `invite.groupAvatar.files.updatedAt` (string, required)
    Example: "2022-03-10T16:15:50Z"

  - `invite.groupAvatar.files.type` (string, required)
    File type
    Enum: "VIDEO", "IMAGE", "AUDIO", "DOCUMENT", "OTHER"

  - `invite.groupAvatar.tags` (array, required)
    List of tags attached to upload
    Enum: "Post", "Avatar", "Header", "Album", "Emoji", "Event"

  - `invite.groupAvatar.error` (string,null)
    Upload processing error

  - `invite.groupAvatar.cached` (boolean)
    true if cached

  - `invite.groupAvatar.logs` (string,null)
    Logs

  - `invite.groupAvatar.remote` (boolean)
    true if this upload is remote

  - `invite.groupAvatar.createdAt` (string, required)
    Example: "2022-03-10T16:15:50Z"

  - `invite.groupAvatar.updatedAt` (string, required)
    Example: "2022-03-10T16:15:50Z"

  - `invite.createdAt` (string, required)
    When the invitation was created
    Example: "2022-03-10T16:15:50Z"

  - `invite.updatedAt` (string, required)
    When the invitation was last updated
    Example: "2022-03-10T16:15:50Z"

  - `emailSent` (boolean, required)
    Whether an invitation email was sent from this server

## Response 400 fields (application/json):

  - `errorCode` (string, required)
    Error code

  - `message` (string, required)
    Error message

  - `docUrl` (string)
    Link to documentation

## Response 401 fields (application/json):

  - `errorCode` (string, required)
    Error code

  - `message` (string, required)
    Error message

  - `docUrl` (string)
    Link to documentation

## Response 403 fields (application/json):

  - `errorCode` (string, required)
    Error code

  - `message` (string, required)
    Error message

  - `docUrl` (string)
    Link to documentation

## Response 404 fields (application/json):

  - `errorCode` (string, required)
    Error code

  - `message` (string, required)
    Error message

  - `docUrl` (string)
    Link to documentation

## Response 409 fields (application/json):

  - `errorCode` (string, required)
    Error code

  - `message` (string, required)
    Error message

  - `docUrl` (string)
    Link to documentation